任务报告推送（2025‑05‑15 版）

注册回调即可实时接收任务报告，新增集团客户推送支持。

• 兼容性：2025‑05‑15（含）之后新建或重新保存的订阅将采用本文描述的 新顶级字段格式；
• 已生效的旧订阅保持两级结构（appId + payload），功能不受影响。
• 新顶级字段（与 appId、payload 同级）：
• 集团客户：同一集团下的多租户可以在一个回调地址统一接收推送，通过新增顶级字段区分不同产品与业务。

回调注册要求

1. 语言：符合 IETF BCP 47（如 en-US、zh-CN）。

2. 回调：

   • url 例如 https://{{host}}/callback，HTTP 方法 POST。
   • appId 例如 24416c36-d9c7-4d74-a047-d6ca461fxxxx（用于鉴权）。

示例 curl

curl --location 'https://{{host}}/callback' \
--header 'accept: */*' \
--header 'Content-Type: application/json' \
--data '{
  "messageTypeId": 2,
  "productId": "TEST00-0000-000-XXXX",
  "messageId": "TEST00-0000-000-XXXX:2:684c183c-4ad9-467b-ac7c-55835255AAAA",
  "traceId": "3d54fe90c9a34c20b600e3b7fa9af254",
  "messageTimestamp": 1715769600000,
  "appId": "24416c36-aaaa-4d74-aaaa-d6ca461faaaa",
  "payload": {
    "serialNumber": "TEST00-0000-000-XXXX",
    "modelTypeCode": "Scrubber S1",
    "taskReport": {
      "id": "684c183c-4ad9-467b-ac7c-55835255AAAA",
      "taskId": "233123123-d9c7-4d74-a047-d6ca461faaaa",
      "planId": "233123123-d9c7-4d74-a047-d6ca461faaaa",
      "taskInstanceId": "893cbadf-3bb1-45be-b7ef-d590d54fAAAA",
      "displayName": "ceshi2",
      "startTime": 1714124784000,
      "endTime": 1714124890000,
      "robot": "S2153",
      "robotSerialNumber": "TEST00-0000-000-XXXX",
      "operator": "admin",
      "completionPercentage": 0.156,
      "durationSeconds": 106,
      "plannedCleaningAreaSquareMeter": 67.425,
      "actualCleaningAreaSquareMeter": 10.548,
      "efficiencySquareMeterPerHour": 407.965,
      "plannedPolishingAreaSquareMeter": null,
      "actualPolishingAreaSquareMeter": null,
      "waterConsumptionLiter": 0.0,
      "startBatteryPercentage": 38.0,
      "endBatteryPercentage": 38.0,
      "consumablesResidualPercentage": {
        "brush": 100.0,
        "filter": 100.0,
        "suctionBlade": 100.0
      },
      "cleaningMode": "清扫",
      "taskEndStatus": 1,
      "subTasks": [
        {
          "mapId": "370192bd-fe7f-40d0-8d0a-4360415bb8cf",
          "mapName": "ceshi2",
          "actualCleaningAreaSquareMeter": 10.548,
          "taskId": "233123123-d9c7-4d74-a047-d6ca461faaaa"
        }
      ],
      "taskReportPngUri": "https://bot.release.gs-robot.com/robot-task/task/report/png/v2/en/684c183c-4ad9-467b-ac7c-55835255aaaa",
      "areaNameList": "2_area1、area2、area3、area4,3_area1、area2、area3"
    }
  }
}'

顶级字段说明

字段	类型	描述
appId	String	用于鉴权，保持不变
payload	Object	业务数据，结构与旧版保持一致
messageTypeId	Int	推送类型：1 事件，2 任务报告，3 排班任务
productId	String	机器人序列号（SN）
messageId	String	全局唯一消息 ID，格式 {productId}:{messageTypeId}:{businessId}
traceId	String	请求链路追踪 ID
messageTimestamp	Long	推送触发时间戳（毫秒）

参数描述

字段名称	类型	描述	示例
payload.serialNumber	String	机器人序列号	TEST00-0000-000-XXXX
payload.modelTypeCode	String	机器人型号代码	Scrubber 50H
payload.taskReport	Object	任务报告	—
payload.taskReport.id	String	任务报告 ID	684c183c-4ad9-467b-ac7c-55835255AAAA
payload.taskReport.taskId	String	静态任务 ID	233123123-d9c7-4d74-a047-d6ca461faaaa
payload.taskReport.planId	String	调度计划 ID	233123123-d9c7-4d74-a047-d6ca461faaaa
payload.taskReport.taskInstanceId	String	任务实例 ID	893cbadf-3bb1-45be-b7ef-d590d54fAAAA
payload.taskReport.displayName	String	任务可读名称	10楼清洁任务
payload.taskReport.startTime	Long	任务开始时间戳（毫秒）	1714290913000
payload.taskReport.endTime	Long	任务结束时间戳（毫秒）	1714290952000
payload.taskReport.robot	String	机器人可读名称	S2153
payload.taskReport.robotSerialNumber	String	机器人序列号	GS000-XXXX-XXX-XXXX
payload.taskReport.operator	String	任务操作员	Mike
payload.taskReport.completionPercentage	Double	完成百分比（0‑1）	0.55
payload.taskReport.durationSeconds	Integer	持续时间（秒）	300
payload.taskReport.plannedCleaningAreaSquareMeter	Double	计划清洁面积（㎡）	200.5
payload.taskReport.actualCleaningAreaSquareMeter	Double	实际清洁面积（㎡）	100.2
payload.taskReport.efficiencySquareMeterPerHour	Double	清洁效率（㎡/h）	300.7
payload.taskReport.plannedPolishingAreaSquareMeter	Double	计划抛光面积（㎡）	200.5
payload.taskReport.actualPolishingAreaSquareMeter	Double	实际抛光面积（㎡）	200.5
payload.taskReport.waterConsumptionLiter	Double	水耗（L）	5.0
payload.taskReport.startBatteryPercentage	Double	起始电量（%）	70.0
payload.taskReport.endBatteryPercentage	Double	结束电量（%）	40.0
payload.taskReport.consumablesResidualPercentage	Object	消耗品剩余百分比	—
payload.taskReport.consumablesResidualPercentage.brush	Double	刷子寿命（%）	50.0
payload.taskReport.consumablesResidualPercentage.filter	Double	过滤器寿命（%）	50.0
payload.taskReport.consumablesResidualPercentage.suctionBlade	Double	吸尘刮刀寿命（%）	50.0
payload.taskReport.cleaningMode	String	清洁模式	扫地
payload.taskReport.taskEndStatus	Integer	结束状态：-1未知，0正常，1手动，2异常，3启动失败	0
payload.taskReport.subTasks	Array	子任务列表	—
payload.taskReport.subTasks[0].mapId	String	地图 ID	370192bd-fe7f-40d0-8d0a-4360415baaaa
payload.taskReport.subTasks[0].mapName	String	地图名称	测试地图
payload.taskReport.subTasks[0].actualCleaningAreaSquareMeter	Double	实际清洁面积（㎡）	10.0
payload.taskReport.subTasks[0].taskId	String	子任务 ID	233123123-d9c7-4d74-a047-d6ca461faaaa
payload.taskReport.taskReportPngUri	String	任务报告 PNG URI	https://bot.gs-robot.com/robot-task/task/report/png/v2/en/47e3628b-a2b9-4124-bbbc-45e0d4bfaaaa
payload.taskReport.areaNameList	String	分区名称列表（floor_area1_area2...）	2_area1、area2、area3